Skip to content

docs(canister-management): add canister migration guide, improve subnet selection, reorder sidebar#245

Open
marc0olo wants to merge 10 commits into
mainfrom
docs/subnet-selection-improvements
Open

docs(canister-management): add canister migration guide, improve subnet selection, reorder sidebar#245
marc0olo wants to merge 10 commits into
mainfrom
docs/subnet-selection-improvements

Conversation

@marc0olo
Copy link
Copy Markdown
Member

@marc0olo marc0olo commented May 12, 2026 •
edited
Loading

Closes #233.

Summary

Subnet selection (guides/canister-management/subnet-selection.md):

  • --proxy section rewritten: notes --proxy/--subnet mutual exclusivity; adds the exact ProxyArgs/ProxyResult Candid interface; clarifies cycles come from the proxy canister's own balance, not the caller's identity balance on the cycles ledger
  • Troubleshooting "wrong subnet" bullet: shortened to one sentence + link now that a dedicated migration guide exists
  • Troubleshooting "wrong subnet" — full migration description: fixed step ordering (snapshot deletion on target belongs within state transfer, before copying settings); added missing "stop target" prerequisite; added cycles burn warning
  • Sidebar order: 8 → 9

New page: Canister migration (guides/canister-management/canister-migration.md, sidebar order 10):

  • Decision table with two approaches: snapshot transfer (new ID, source retained) vs. full migration via icp canister migrate-id (ID preserved, source deleted)
  • "The canister ID must not change when" — covers tECDSA/tSchnorr, vetKeys, external references
  • :::danger callout explains the recovery window accurately: state and keys split between canisters after snapshot transfer; recovery possible until source is deleted; permanent once source is gone
  • Full step-by-step workflows for both approaches, verified against icp-cli source
  • Critical gotchas surfaced: snapshot must be deleted on target before migrate-id; source cycles burned; target must be stopped; NNS migration canister controller must be removed after
  • Interruption recovery (--resume-watch, --skip-watch) documented

Canister lifecycle (guides/canister-management/lifecycle.mdx):

  • Migration section reduced from 22 lines to 2 sentences: removed duplicate table, stale "load-bearing" phrasing, and raw GitHub link; replaced with a pointer to the new migration guide
  • Added subnet selection and canister migration to Next steps
  • Fixed [principal] link to point to concepts/principals.md instead of concepts/canisters.md

Canister snapshots (guides/canister-management/snapshots.md):

  • Next steps: added link to canister migration guide
  • Removed reference to undocumented load_canister_snapshot protocol detail; replaced with accurate icp-cli-level constraint

Sidebar reorder (core operations → build quality → deployment topology):

Page Old New
Cycles management 7 4
Canister optimization 4 6
Reproducible builds 6 7
Large Wasm modules 10 8
Subnet selection 8 9
Canister migration — 10

Sync recommendation

canister-migration.md: informed by dfinity/icp-cli docs/guides/canister-migration.md; dfinity/icp-cli docs/reference/cli.md

subnet-selection.md: informed by dfinity/icp-cli docs/guides/deploying-to-specific-subnets.md; dfinity/icp-cli docs/guides/canister-migration.md; dfinity/icp-cli crates/icp-canister-interfaces/src/proxy.rs; dfinity/icp-cli crates/icp-cli/src/operations/proxy.rs; dfinity/icp-cli docs/reference/cli.md

@marc0olo
docs(canister-management): improve subnet selection guide
9d2b0ad 
Addresses all issues raised in #233:

- Rename "Colocation with an existing canister" to "Colocation via proxy
  canister" and expand it with three targeted fixes:
  - Clarify that --proxy and --subnet are mutually exclusive
  - Add the full ProxyArgs/ProxyResult Candid interface so developers know
    exactly what their proxy canister must implement
  - Explain the cycles model: --cycles passes a value through ProxyArgs.cycles
    and is paid from the proxy canister's own balance, not the caller's wallet
- Fix the "by default" phrasing in troubleshooting: replace with "without
  using icp canister migrate-id"
- Add a direct link to the canister migration guide in the troubleshooting
  entry and in Next steps
@marc0olo marc0olo requested a review from a team as a code owner May 12, 2026 10:46
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 12, 2026 •
edited
Loading

🤖 Here's your preview: https://lvbky-nyaaa-aaaam-ai7tq-cai.icp0.io

marc0olo
marc0olo commented May 12, 2026
View reviewed changes
Comment thread docs/guides/canister-management/subnet-selection.md Outdated
@marc0olo
docs(canister-management): fix accuracy and precision in subnet selec…
3b6d0b3 
…tion guide

Address PR #245 review feedback and source-verified inaccuracies:

- Cycles model: replace "from your wallet" with "from your identity's
  balance on the cycles ledger" (wallet is a deprecated dfx concept)
- Migration description: fix step ordering — snapshot deletion on target
  belongs within the state transfer phase, before copying settings, not
  after; add the missing "stop the target canister" prerequisite for
  migrate-id; add the cycles burn warning (source cycles burned, target
  needs funding in advance)
- Next steps snapshot link: add section anchor pointing directly to the
  state-transfer example; sharpen the label
- Upstream comment: add proxy.rs and canister-migration.md references
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 12, 2026

Feedback addressed:

  • "from your wallet": replaced with "from your identity's balance on the cycles ledger" — wallet is a deprecated dfx concept
  • Migration description step ordering: the original text had snapshot deletion after copying settings; the actual guide puts it within the state-transfer step (before copying settings). Fixed. Also added the missing "stop the target canister" prerequisite for migrate-id, and the cycles burn warning (source cycles burned on deletion, top up target in advance)
  • Snapshot Next steps link: now points directly to #example-transferring-state-between-canisters with a sharper label
  • Upstream comment: added proxy.rs and canister-migration.md as sources

marc0olo added 8 commits May 12, 2026 13:04
@marc0olo
docs(canister-management): add canister migration guide and update cr…
3da262f 
…oss-references

Add docs/guides/canister-management/canister-migration.md covering both
migration paths: snapshot transfer (new canister ID) and full migration
with ID preservation via icp canister migrate-id. The guide documents the
step ordering that matters for correctness — snapshot deletion on the target
before migrate-id, target must be stopped, source cycles are burned — and
includes interruption recovery and NNS controller cleanup.

Update cross-references:
- subnet-selection.md: replace external cli.internetcomputer.org links
  with internal links to canister-migration.md
- snapshots.md: add canister migration to Next steps
- large-wasm.md: bump sidebar order from 9 to 10 to accommodate
  canister-migration at order 9 (after subnet-selection)
@marc0olo
docs(canister-management): tighten cross-references and add danger ca…
8b21f00 
…llout

- subnet-selection troubleshooting: shorten the "ID must be preserved"
  bullet to one sentence + link; detail belongs in the migration guide
- canister-migration: add :::danger callout after the load-bearing ID
  cases to make permanent, irreversible loss visible before users choose
  an approach
- subnet-selection Next steps: tighten snapshot label to "to another
  canister" (download/upload works for any target, not just cross-subnet)
- snapshots Next steps: same label fix
@marc0olo
docs(canister-management): remove undocumented protocol reference, ti…
fae7ad6 
…ghten copy

- Remove load_canister_snapshot parenthetical from snapshots.md and
  canister-migration.md: the protocol-level cross-canister same-subnet
  restore is real (per IC interface spec) but the icp-cli doesn't expose
  it and we have no guide for it; replace with the accurate icp-cli-level
  constraint ("snapshot must exist on target before restore")
- Trim subnet-selection troubleshooting bullet to one sentence + link
- Snapshots Next steps: "to another canister" instead of "to a canister
  on a different subnet" (download/upload works for any target canister)
@marc0olo
docs(canister-management): fix danger callout accuracy in migration g…
4f8def3 
…uide

Two corrections in the "Choosing your approach" section:

- Replace "load-bearing" with "whether the canister ID can change" and
  "The canister ID cannot change when" — avoids informal construction
  metaphor, says the same thing in plain ICP terms
- Rewrite danger callout: "no recovery path" was wrong. Snapshot transfer
  retains the source canister, so the original tECDSA/vetKeys remain
  accessible through it until the source is deleted. Callout now explains
  the recovery window (stop target, switch back, do full migration) and
  names the actual point of no return (source canister deleted).
@marc0olo
fix: remove em-dashes from canister-migration.md
9705127
@marc0olo
docs: use 'must not change' over 'cannot change' in migration guide
0915970
@marc0olo
docs(canister-management): reorder sidebar and slim lifecycle migrati…
7e6d3b3 
…on section

Sidebar reorder (core ops → build quality → deployment topology):
- cycles-management: 7 → 4 (fundamental, not advanced)
- snapshots: 5 unchanged (stays after cycles, supports upgrade safety)
- optimization: 4 → 6
- reproducible-builds: 6 → 7
- large-wasm: 10 → 8 (closes build quality cluster)
- subnet-selection: 8 → 9
- canister-migration: 9 → 10

lifecycle.mdx migration section: replace 22-line duplicate
(table + bullets + GitHub raw link) with a two-sentence pointer to
canister-migration.md; add subnet selection and canister migration
to Next steps
@marc0olo
fix(lifecycle): link 'principal' to concepts/principals.md
3add58c
@marc0olo marc0olo changed the title docs(canister-management): improve subnet selection guide docs(canister-management): add canister migration guide, improve subnet selection, reorder sidebar May 12, 2026
marc0olo added a commit that referenced this pull request May 12, 2026
@marc0olo
docs: review fixes for best-practices gaps PR
7b86eda 
- Fix Map.entries() call in pagination.md Motoko example (no comparator arg)
- Remove unused import Iter in pagination.md
- Add sidebar orders to pagination.md (6), idempotency.md (5),
  trust-in-canisters.md (11), troubleshooting.md (12); orders 11-12
  leave room for canister-migration.md (10) from PR #245
- Add subnet migration subsection to troubleshooting.md latency problem
- Fix icp canister status flag: -n ic -> -e ic in trust-in-canisters.md
- Link SNS term in trust spectrum table to concepts/sns-framework.md
- Add pagination.md to inter-canister-calls.mdx Next steps
@marc0olo marc0olo mentioned this pull request May 12, 2026
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Review and improve subnet selection guide

1 participant

@marc0olo